~ chicken-core (master) /manual/Module (chicken memory)
Trap1[[tags: manual]]2[[toc:]]34== Module (chicken memory)56The procedures from this module operate directly on memory, at a very7low level. This makes them unsafe, unlike most other Scheme8procedures. '''Use at your own risk.'''910=== Foreign pointers1112The abstract class of ''pointer'' is divided into 2 categories:1314; ''pointer object'' : is a regular or [[#Tagged pointers|tagged]] foreign pointer object.1516; ''pointer-like object'' : is a closure, port, [[Module (chicken locative)|locative]], or a pointer object.1718Note that Locatives, while technically pointers, are not considered a ''pointer19object'', but a ''pointer-like object''. The distinction is artificial.202122==== address->pointer2324<procedure>(address->pointer ADDRESS)</procedure>2526Creates a new foreign pointer object initialized to point to the address27given in the integer {{ADDRESS}}.282930==== allocate3132<procedure>(allocate BYTES)</procedure>3334Returns a foreign pointer object to a freshly allocated region of static35memory.3637This procedure could be defined as follows:3839<enscript highlight=scheme>40(define allocate (foreign-lambda c-pointer "malloc" integer))41</enscript>424344==== free4546<procedure>(free POINTER)</procedure>4748Frees the memory pointed to by {{POINTER}}.4950This procedure could be defined as follows:5152<enscript highlight=scheme>53(define free (foreign-lambda void "free" c-pointer))54</enscript>555657==== object->pointer5859<procedure>(object->pointer X)</procedure>6061Returns a foreign pointer object pointing to the Scheme object X, which should62be a non-immediate object. ("foreign" here is a bit of a misnomer.)6364Note that data in the garbage collected heap moves during garbage collection.656667==== pointer->object6869<procedure>(pointer->object POINTER)</procedure>7071Returns the Scheme object pointed to by the pointer object {{POINTER}}.7273Whether the {{POINTER}} actually points to a Scheme object is not guaranteed. Use74at your own risk.7576==== pointer?7778<procedure>(pointer? X)</procedure>7980Returns {{#t}} if {{X}} is a pointer object, or {{#f}} otherwise.818283==== pointer-like?8485<procedure>(pointer-like? X)</procedure>8687Returns {{#t}} if {{X}} is a pointer-like object, or {{#f}} otherwise.888990==== pointer=?9192<procedure>(pointer=? POINTER*1 POINTER*2)</procedure>9394Returns {{#t}} if the pointer-like objects {{POINTER*1}} and {{POINTER*2}} point95to the same address, or {{#f}} otherwise.969798==== pointer->address99100<procedure>(pointer->address POINTER*)</procedure>101102Returns the address, to which the pointer-like object {{POINTER*}} points.103104105==== pointer+106107<procedure>(pointer+ POINTER* N)</procedure>108109Returns a new foreign pointer object representing the pointer-like object110{{POINTER*}} address value increased by the byte-offset {{N}}.111112Use of anything other than a pointer object as an argument is questionable.113114115==== align-to-word116117<procedure>(align-to-word POINTER*-OR-INT)</procedure>118119Accepts either a pointer-like object or an integer as the argument and returns120a new foreign pointer or integer aligned to the native word size of the host121platform.122123Use of anything other than an integer or pointer object as an argument is124questionable.125126127=== SRFI-4 Foreign pointers128129These procedures actually accept a pointer-like object as the {{POINTER}} argument.130However, as usual, use of anything other than a pointer object is questionable.131132133==== pointer-u8-ref134135<procedure>(pointer-u8-ref POINTER)</procedure>136137Returns the unsigned byte at the address designated by {{POINTER}}.138139140==== pointer-s8-ref141142<procedure>(pointer-s8-ref POINTER)</procedure>143144Returns the signed byte at the address designated by {{POINTER}}.145146147==== pointer-u16-ref148149<procedure>(pointer-u16-ref POINTER)</procedure>150151Returns the unsigned 16-bit integer at the address designated by {{POINTER}}.152153154==== pointer-s16-ref155156<procedure>(pointer-s16-ref POINTER)</procedure>157158Returns the signed 16-bit integer at the address designated by {{POINTER}}.159160161==== pointer-u32-ref162163<procedure>(pointer-u32-ref POINTER)</procedure>164165Returns the unsigned 32-bit integer at the address designated by {{POINTER}}.166167168==== pointer-s32-ref169170<procedure>(pointer-s32-ref POINTER)</procedure>171172Returns the signed 32-bit integer at the address designated by {{POINTER}}.173174==== pointer-u64-ref175176<procedure>(pointer-u64-ref POINTER)</procedure>177178Returns the unsigned 64-bit integer at the address designated by {{POINTER}}.179180181==== pointer-s64-ref182183<procedure>(pointer-s64-ref POINTER)</procedure>184185Returns the signed 64-bit integer at the address designated by {{POINTER}}.186187188==== pointer-f32-ref189190<procedure>(pointer-f32-ref POINTER)</procedure>191192Returns the 32-bit float at the address designated by {{POINTER}}.193194195==== pointer-f64-ref196197<procedure>(pointer-f64-ref POINTER)</procedure>198199Returns the 64-bit double at the address designated by {{POINTER}}.200201202==== pointer-u8-set!203204<procedure>(pointer-u8-set! POINTER N)</procedure><br>205<procedure>(set! (pointer-u8-ref POINTER) N)</procedure>206207Stores the unsigned byte {{N}} at the address designated by {{POINTER}}.208209210==== pointer-s8-set!211212<procedure>(pointer-s8-set! POINTER N)</procedure><br>213<procedure>(set! (pointer-s8-ref POINTER) N)</procedure>214215Stores the signed byte {{N}} at the address designated by {{POINTER}}.216217218==== pointer-u16-set!219220<procedure>(pointer-u16-set! POINTER N)</procedure><br>221<procedure>(set! (pointer-u16-ref POINTER) N)</procedure>222223Stores the unsigned 16-bit integer {{N}} at the address designated by {{POINTER}}.224225226==== pointer-s16-set!227228<procedure>(pointer-s16-set! POINTER N)</procedure><br>229<procedure>(set! (pointer-s16-ref POINTER) N)</procedure>230231Stores the signed 16-bit integer {{N}} at the address designated by {{POINTER}}.232233234==== pointer-u32-set!235236<procedure>(pointer-u32-set! POINTER N)</procedure><br>237<procedure>(set! (pointer-u32-ref POINTER) N)</procedure>238239Stores the unsigned 32-bit integer {{N}} at the address designated by {{POINTER}}.240241242==== pointer-s32-set!243244<procedure>(pointer-s32-set! POINTER N)</procedure><br>245<procedure>(set! (pointer-s32-ref POINTER) N)</procedure>246247Stores the 32-bit integer {{N}} at the address designated by {{POINTER}}.248249250==== pointer-u64-set!251252<procedure>(pointer-u64-set! POINTER N)</procedure><br>253<procedure>(set! (pointer-u64-ref POINTER) N)</procedure>254255Stores the unsigned 64-bit integer {{N}} at the address designated by {{POINTER}}.256257258==== pointer-s64-set!259260<procedure>(pointer-s64-set! POINTER N)</procedure><br>261<procedure>(set! (pointer-s64-ref POINTER) N)</procedure>262263Stores the 64-bit integer {{N}} at the address designated by {{POINTER}}.264265266==== pointer-f32-set!267268<procedure>(pointer-f32-set! POINTER N)</procedure><br>269<procedure>(set! (pointer-f32-ref POINTER) N)</procedure>270271Stores the 32-bit floating-point number {{N}} at the address designated by {{POINTER}}.272273274==== pointer-f64-set!275276<procedure>(pointer-f64-set! POINTER N)</procedure><br>277<procedure>(set! (pointer-f64-ref POINTER) N)</procedure>278279Stores the 64-bit floating-point number {{N}} at the address designated by {{POINTER}}.280281282283=== Tagged pointers284285''Tagged'' pointers are foreign pointer objects with an extra tag object.286287288==== tag-pointer289290<procedure>(tag-pointer POINTER* TAG)</procedure>291292Creates a new tagged foreign pointer object from the pointer-like object293{{POINTER*}} with the tag {{TAG}}, which may an arbitrary Scheme object.294295Use of anything other than a pointer object is questionable.296297==== tagged-pointer?298299<procedure>(tagged-pointer? X [TAG])</procedure>300301Returns {{#t}} if {{X}} is a tagged foreign pointer object, or {{#f}} otherwise.302303Further, returns {{#t}} when {{X}} has the optional tag {{TAG}} (using an304{{equal?}} comparison), or {{#f}} otherwise.305306307==== pointer-tag308309<procedure>(pointer-tag POINTER*)</procedure>310311If {{POINTER}} is a tagged foreign pointer object, its tag is returned. If {{POINTER*}}312is any other kind of pointer-like object {{#f}} is returned. Otherwise an313error is signalled.314315316=== Pointer vectors317318''Pointer vectors'' are specialized and space-efficient vectors for319foreign pointer objects. All procedures defined below that accept320a pointer object allow {{#f}} as an alternative representation of321the {{NULL}}-pointer.322323324==== make-pointer-vector325326<procedure>(make-pointer-vector LENGTH [INIT])</procedure>327328Creates a pointer-vector of the given length and optionally initializes each329element to {{INIT}}, which should be a pointer or {{#f}}, which represents the330{{NULL}} pointer.331332==== pointer-vector?333334<procedure>(pointer-vector? X)</procedure>335336Returns {{#t}} if {{X}} is a pointer-vector or {{#f}} otherwise.337338==== pointer-vector339340<procedure>(pointer-vector POINTER ...)</procedure>341342Returns a pointer-vector from the given pointer arguments.343344==== pointer-vector-length345346<procedure>(pointer-vector-length POINTERVECTOR)</procedure>347348Returns the length of the given pointer-vector.349350==== pointer-vector-ref351352<procedure>(pointer-vector-ref POINTERVECTOR INDEX)</procedure>353354Returns the pointer at {{INDEX}} in the given pointer-vector or355{{#f}} if the element is a {{NULL}}- pointer.356357==== pointer-vector-set!358359<procedure>(pointer-vector-set! POINTERVECTOR INDEX POINTER)</procedure>360361Sets the element at the position {{INDEX}} in the given pointer-vector to362{{POINTER}}. The alternative syntax363364 (set! (pointer-vector-ref POINTERVECTOR INDEX) POINTER)365366is also allowed.367368==== pointer-vector-fill!369370<procedure>(pointer-vector-fill! POINTERVECTOR POINTER)</procedure>371372Set every element in the {{POINTERVECTOR}} to {{POINTER}}.373374375=== Moving memory376377==== move-memory!378379<procedure>(move-memory! FROM TO [BYTES [FROM-OFFSET [TO-OFFSET]]])</procedure>380381Copies {{BYTES}} bytes of memory from {{FROM}} to {{TO}}. {{FROM}} and {{TO}}382may be strings, bytevectors, [[Module srfi-4|SRFI-4 number-vectors]], memory383mapped files, foreign pointers (as obtained from a call to {{foreign-lambda}},384for example), tagged-pointers or locatives. if {{BYTES}} is not given and the385size of the source or destination operand is known then the maximal number of386bytes will be copied. Moving memory to the storage returned by locatives will387cause havoc, if the locative refers to containers of non-immediate data, like388vectors or pairs.389390The additional fourth and fifth argument specify starting offsets (in bytes)391for the source and destination arguments.392393Signals an error if any of the above constraints is violated.394395---396Previous: [[Module (chicken locative)]]397398Next: [[Module (chicken memory representation)]]